Feature: Custom Entity API by onebeastchris · Pull Request #6010 · GeyserMC/Geyser

onebeastchris · 2025-11-25T21:38:25Z

Introducing: Custom Entities!

tl;dr: with this PR, you can summon custom bedrock entities that replace the vanilla mapping

Additions

CustomEntityDefinition / GeyserEntityDefinition: Representations of custom, and vanilla Bedrock entities. Unlike custom blocks/items, bedrock entities have fewer properties that are defined in advance; it's just the identifier, and the Bedrock Entity Properties. Setting entity properties was introduced in a previous PR; and works the same way.
JavaEntityType: Represents a vanilla Java entity type, with the width / height / type identifier, as well as the default Bedrock entity associated with it. Similarly, CustomJavaEntityType represents a non-vanilla Java entity - however, that part of the API still needs some more work and should be regarded as unstable.
GeyserEntityDataType / GeyserEntityDataTypes: These are representations of various Bedrock entity metadata types, such as scale, width, height, variant, or color. Further, vertical_offset has been added as a "custom" data type to allow setting a vertical entity offset.
The GeyserEntity class has seen major additions! You can now query the entities' associated Bedrock entity definition, Java position, the Geyser id, UUID, or update / query the aforementioned data types.
You can now look up GeyserEntity instances using the entity UUID or Geyser entity ID, additionally to the Java entity id.

New Events

GeyserDefineEntitiesEvent: Allows registering custom Bedrock entities and querying existing entities.
SessionSpawnEntityEvent: Base entity spawn event extended by the server events. With it, you can set a pre-spawn consumer, and switch the Bedrock entity definition, or cancel the entity spawn outright.
ServerAttachParrotsEvent: Called every time a parrot is spawned on the player entity
ServerSpawnEntityEvent: Called for every non-player entity that is spawned by the Java server. Within this event, you can query the Java entity type, uuid, and entity id (and also have access to the methods provided by the SessionSpawnEntityEvent!

Here's some example code of the API in action:
https://gist.github.com/onebeastchris/1521ab585669792a79a9558d9d069834

Internal changes:

Bedrock entity definitions are now split from the Java entity definitions.
There is now a EntitySpawnContext that is passed in entity constructors - instead of many arguments. This should make it easier to add new entities, call events, or add more arguments in the future
Entity offsets are now properly handled in the base Entity class - no more hacks in TntEntity and the like!

TO-DO's:

Finish VanillaEntityBases split; potentially allow non-vanilla entities to extend those?
Debug logging for modifications
Sensible limits for scale / height / width
Docs

EXPERIMENTAL downloads:

…nition, create GeyserEntityType, target custom entities MCPL

…can now be modified in the ServerSpawnEntityEvent

Copilot

Pull request overview

This PR implements a Custom Entity API for Geyser, refactoring entity creation to use a context-based approach instead of individual constructor parameters. The changes enable support for custom entities while modernizing the entity type system.

Key Changes:

Introduced EntitySpawnContext as a unified way to pass entity creation parameters
Renamed EntityDefinition to EntityTypeDefinition for clarity
Changed EntityType to BuiltinEntityType to distinguish vanilla entities from custom ones
Added new registries for custom entities and Bedrock entity definitions
Refactored 100+ entity class constructors to use the new context pattern

Reviewed changes

Copilot reviewed 192 out of 193 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
gradle/libs.versions.toml	Updated mcprotocollib version to feature branch for custom entities
Test files	Updated mock entity creation to use EntitySpawnContext
StatisticsUtils.java	Changed entity name translation to use GeyserEntityType
EntityUtils.java	Refactored entity type comparisons from switch to if-else with .is() method
Translator classes	Updated to use BuiltinEntityType and new entity creation patterns
Session/cache classes	Updated entity instantiation with EntitySpawnContext
Registry classes	Added new registries for custom entity support
Entity hierarchy	All entity constructors refactored to accept EntitySpawnContext

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

...a/org/geysermc/geyser/translator/protocol/bedrock/entity/player/input/BedrockMovePlayer.java

core/src/main/java/org/geysermc/geyser/util/EntityUtils.java

...in/java/org/geysermc/geyser/translator/protocol/java/entity/JavaSetPassengersTranslator.java

core/src/main/java/org/geysermc/geyser/level/physics/CollisionManager.java

core/src/main/java/org/geysermc/geyser/entity/EntityTypeDefinition.java

core/src/main/java/org/geysermc/geyser/entity/BedrockEntityDefinition.java

core/src/main/java/org/geysermc/geyser/entity/EntityTypeDefinition.java

core/src/main/java/org/geysermc/geyser/entity/NonVanillaEntityTypeDefinition.java

core/src/main/java/org/geysermc/geyser/entity/VanillaEntityType.java

… API Javadocs

Copilot

Pull request overview

Copilot reviewed 222 out of 223 changed files in this pull request and generated 11 comments.

Comments suppressed due to low confidence (1)

core/src/main/java/org/geysermc/geyser/session/GeyserSession.java:610

getAttachedFireworkRockets exposes the internal representation stored in field attachedFireworkRockets. The value may be modified after this call to getAttachedFireworkRockets.
getAttachedFireworkRockets exposes the internal representation stored in field attachedFireworkRockets. The value may be modified after this call to getAttachedFireworkRockets.
getAttachedFireworkRockets exposes the internal representation stored in field attachedFireworkRockets. The value may be modified after this call to getAttachedFireworkRockets.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

core/src/main/java/org/geysermc/geyser/util/EntityUtils.java

core/src/main/java/org/geysermc/geyser/session/cache/waypoint/GeyserWaypoint.java

core/src/main/java/org/geysermc/geyser/entity/EntityTypeDefinition.java

core/src/main/java/org/geysermc/geyser/entity/GeyserEntityType.java

core/src/main/java/org/geysermc/geyser/entity/VanillaEntityType.java

core/src/main/java/org/geysermc/geyser/entity/type/Entity.java

Copilot

Pull request overview

Copilot reviewed 130 out of 131 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 130 out of 131 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

core/src/main/java/org/geysermc/geyser/impl/entity/HitboxImpl.java

core/src/main/java/org/geysermc/geyser/item/parser/ItemStackParser.java

core/src/main/java/org/geysermc/geyser/impl/entity/HitboxImpl.java

…tities-api

Copilot

Pull request overview

Copilot reviewed 130 out of 131 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

core/src/main/java/org/geysermc/geyser/entity/type/player/PlayerEntity.java

+            if (!context.callParrotEvent(this, variant.getAsInt(), !isLeft)) {
+                GeyserImpl.getInstance().getLogger().debug(session, "Cancelled parrot spawn as definition is null!");
+                return;


core/src/main/java/org/geysermc/geyser/network/UpstreamPacketHandler.java

+            GeyserImpl.getInstance().getLogger().debug("Client %s tried to request pack with an invalid id %s)",
                session.bedrockUsername(), id);


This will be later reworked to allow setting a height + width combo that accounts for the entity pose. For now, it's a general override

Copilot

Pull request overview

Copilot reviewed 130 out of 131 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

core/src/main/java/org/geysermc/geyser/entity/type/player/SessionPlayerEntity.java

        } else if (entity == null && this.vehicle instanceof BoatEntity) {
-            this.vehicle.setBoundingBoxWidth(this.vehicle.getDefinition().width());
-            this.vehicle.setBoundingBoxHeight(this.vehicle.getDefinition().height());
+            this.vehicle.setBoundingBoxWidth(this.vehicle.getBoundingBoxWidth());
+            this.vehicle.setBoundingBoxHeight(this.vehicle.getBoundingBoxHeight());
            this.vehicle.updateBedrockMetadata();


core/src/main/java/org/geysermc/geyser/entity/GeyserEntityData.java

+    @Override
+    public @Nullable GeyserEntity byJavaId(@NonNegative int javaId) {
+        //noinspection ConstantValue
+        if (javaId < 0) {
+            throw new IllegalArgumentException("entity id cannot be negative! (got: " + javaId + ")");
+        }
+        return session.getEntityCache().getEntityByJavaId(javaId);
+    }
+
+    @Override
+    public @Nullable GeyserEntity byUuid(@NonNull UUID javaUuid) {
+        Objects.requireNonNull(javaUuid, "javaUuid");
+        return session.getEntityCache().getEntityByUuid(javaUuid);
+    }
+
+    @Override
+    public @Nullable GeyserEntity byGeyserId(@NonNegative long geyserId) {
+        //noinspection ConstantValue
+        if (geyserId < 0) {
+            throw new IllegalArgumentException("geyser entity id cannot be negative! (got: " + geyserId + ")");
+        }
+        return session.getEntityCache().getEntityByGeyserId(geyserId);
+    }


…tities-api

Copilot

Pull request overview

Copilot reviewed 130 out of 131 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-20T23:13:08Z

core/src/main/java/org/geysermc/geyser/entity/type/player/SessionPlayerEntity.java

        if (entity instanceof BoatEntity) {
            // These bounding box values are based off 1.21.7
            entity.setBoundingBoxWidth(1.375F);
            entity.setBoundingBoxHeight(0.5625F);
            entity.updateBedrockMetadata();
        } else if (entity == null && this.vehicle instanceof BoatEntity) {
-            this.vehicle.setBoundingBoxWidth(this.vehicle.getDefinition().width());
-            this.vehicle.setBoundingBoxHeight(this.vehicle.getDefinition().height());
+            this.vehicle.setBoundingBoxWidth(this.vehicle.getBoundingBoxWidth());
+            this.vehicle.setBoundingBoxHeight(this.vehicle.getBoundingBoxHeight());
            this.vehicle.updateBedrockMetadata();
        }


When dismounting a boat, this branch attempts to restore the boat bounding box back to its normal size, but it currently sets width/height to their existing values (no-op). As a result, the boat can remain with the enlarged bounding box after the player dismounts, contradicting the comment above and potentially affecting collision/movement. Restore the boat dimensions using the boat’s default size (e.g., from its type definition/base dimensions) instead of the current bounding box values.

…tities-api # Conflicts: # core/src/main/java/org/geysermc/geyser/entity/spawn/EntitySpawnContext.java # core/src/main/java/org/geysermc/geyser/entity/type/BoatEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/Entity.java # core/src/main/java/org/geysermc/geyser/entity/type/EvokerFangsEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/ItemEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/ItemFrameEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/LightningEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/LivingEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/MinecartEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/TextDisplayEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/ThrowableEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/ThrowableItemEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/ArmorStandEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/animal/OcelotEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/animal/SnifferEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/merchant/VillagerEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/monster/CreakingEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/monster/EnderDragonEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/monster/EnderDragonPartEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/monster/EndermanEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/player/AvatarEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/player/SessionPlayerEntity.java # core/src/main/java/org/geysermc/geyser/entity/vehicle/BoatVehicleComponent.java # core/src/main/java/org/geysermc/geyser/entity/vehicle/VehicleComponent.java # core/src/main/java/org/geysermc/geyser/inventory/holder/BlockInventoryHolder.java # core/src/main/java/org/geysermc/geyser/level/physics/CollisionManager.java # core/src/main/java/org/geysermc/geyser/session/cache/BlockBreakHandler.java # core/src/main/java/org/geysermc/geyser/session/cache/BossBar.java # core/src/main/java/org/geysermc/geyser/session/cache/WorldBorder.java # core/src/main/java/org/geysermc/geyser/translator/inventory/chest/DoubleChestInventoryTranslator.java # core/src/main/java/org/geysermc/geyser/translator/level/event/PlaySoundEventTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/bedrock/BedrockInventoryTransactionTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/bedrock/entity/player/input/BedrockMovePlayer.java # core/src/main/java/org/geysermc/geyser/translator/protocol/bedrock/entity/player/input/BedrockPlayerAuthInputTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/java/entity/JavaEntityEventTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/java/entity/player/JavaPlayerLookAtTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/java/entity/player/JavaPlayerPositionTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/java/level/JavaGameEventTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/java/level/JavaLevelParticlesTranslator.java # core/src/main/java/org/geysermc/geyser/util/InventoryUtils.java

…nto feature/custom-entities-api

Copilot

Pull request overview

Copilot reviewed 101 out of 102 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

core/src/main/java/org/geysermc/geyser/entity/type/ItemEntity.java:127

ItemEntity's offset field is updated inside the setOffset override, but moveAbsoluteImmediate uses this.offset as the base offset and then calls setOffset again (including with a negated value when in water). This means that once the offset is negated, the next tick in water will negate it again, causing the entity to flip offset every tick. Keep an immutable/base offset (e.g., from the entity type/initial context) and only apply the temporary sign change to the Bedrock offset without overwriting the base.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-28T20:53:56Z

core/src/main/java/org/geysermc/geyser/entity/spawn/EntitySpawnContext.java

+    public EntitySpawnContext(GeyserSession session, EntityTypeDefinition<?> definition, int javaId, UUID uuid, BedrockEntityDefinition bedrockEntityDefinition, Vector3f position,
+                              Vector3f motion, float yaw, float pitch, float headYaw, float offset, @Nullable Long geyserId) {
        this.session = session;
        this.entityTypeDefinition = definition;
        this.javaId = javaId;
        this.uuid = uuid;
        this.position = position;
        this.offset = definition.offset();
+        this.bedrockEntityDefinition = bedrockEntityDefinition;
        this.motion = motion;


EntitySpawnContext's constructor accepts an offset parameter but ignores it and always assigns this.offset = definition.offset();. This makes it impossible to override the per-spawn offset (e.g., for event-driven/custom entity adjustments) and contradicts the call sites that pass an explicit offset value. Use the provided offset parameter when assigning this.offset (and ensure the other constructors pass the intended value).

eclipseisoffline and others added 13 commits November 22, 2025 17:41

Start working on custom entity API (for real this time)

5a7bf1b

Split EntityDefinition up into EntityDefinition and VanillaEntityDefi…

f4156c6

…nition, create GeyserEntityType, target custom entities MCPL

Allow creating custom entity types from API

0b8678e

Further refactor EntityDefinition, create a Base class

d843745

Work on exposing custom entity definitions in the API

7fe8992

Add EntityDefinition#is

e398c54

Implement CustomEntityDefinition, part one

a3869cf

Move CustomEntityDefinition into custom package

11e6b50

CustomEntityDefinition should extend GeyserEntityDefinition

6fab587

Separate BedrockEntityDefinition from Entity classes

3392510

EntityDefinition -> EntityTypeDefinition

c57f250

Continue splitting bedrock entities from java types

142cbae

Width, height and offset should be tied to the Java entity type; and …

8ff763b

…can now be modified in the ServerSpawnEntityEvent

Copilot AI review requested due to automatic review settings November 25, 2025 21:38

onebeastchris added Work in Progress The issue is currently being worked on. PR: Feature When a PR implements a new feature API The issue/feature request relates to the Geyser API labels Nov 25, 2025

onebeastchris mentioned this pull request Nov 25, 2025

Add support for custom entities in the API #3754

Closed

4 tasks

Copilot started reviewing on behalf of onebeastchris November 25, 2025 21:38 View session

Copilot finished reviewing on behalf of onebeastchris November 25, 2025 21:39

Copilot AI reviewed Nov 25, 2025

View reviewed changes

onebeastchris added 4 commits November 26, 2025 17:08

More work on events, closer to working

b2739e1

Fix startup

52b76f5

Expose geyserId in API, add SessionAttachParrotsEvent

8f8e3be

Rename SessionAttachParrotsEvent -> ServerAttachParrotsEvent, fill in…

9e6b133

… API Javadocs

Copilot AI review requested due to automatic review settings November 27, 2025 21:13

Copilot started reviewing on behalf of onebeastchris November 27, 2025 21:14 View session

Copilot finished reviewing on behalf of onebeastchris November 27, 2025 21:14

Apply some suggestions

75d5f07

Copilot AI reviewed Nov 27, 2025

View reviewed changes

Copilot AI review requested due to automatic review settings February 28, 2026 17:12

Copilot started reviewing on behalf of onebeastchris February 28, 2026 17:12 View session

Copilot AI reviewed Feb 28, 2026

View reviewed changes

onebeastchris added 2 commits March 4, 2026 21:14

Support setting empty hitbox

c35cd1d

Merge branch 'master' into feature/custom-entities-api

05c8c39

Copilot AI review requested due to automatic review settings March 6, 2026 08:39

Copilot started reviewing on behalf of onebeastchris March 6, 2026 08:39 View session

Copilot AI reviewed Mar 6, 2026

View reviewed changes

onebeastchris added 2 commits March 14, 2026 20:19

Merge remote-tracking branch 'upstream/master' into feature/custom-en…

43a3fef

…tities-api

Reviews and comments

0f9ad38

Copilot AI review requested due to automatic review settings March 14, 2026 19:42

Copilot started reviewing on behalf of onebeastchris March 14, 2026 19:43 View session

Copilot AI reviewed Mar 14, 2026

View reviewed changes

onebeastchris added 2 commits March 15, 2026 15:38

Improve height / width handling

d9e0c6b

This will be later reworked to allow setting a height + width combo that accounts for the entity pose. For now, it's a general override

Allow custom height / width to be 0

a21d9e8

Copilot AI review requested due to automatic review settings March 15, 2026 16:36

Copilot started reviewing on behalf of onebeastchris March 15, 2026 16:36 View session

Copilot AI reviewed Mar 15, 2026

View reviewed changes

onebeastchris added 3 commits March 20, 2026 21:49

Merge remote-tracking branch 'upstream/master' into feature/custom-en…

61fbc7a

…tities-api

Merge remote-tracking branch 'upstream/master' into feature/custom-en…

93ddfc7

…tities-api

Likely fix entity registration

34b1d98

Copilot AI review requested due to automatic review settings March 20, 2026 23:07

Copilot started reviewing on behalf of onebeastchris March 20, 2026 23:08 View session

Copilot AI reviewed Mar 20, 2026

View reviewed changes

onebeastchris added 3 commits March 26, 2026 14:35

Merge branch 'master' into feature/custom-entities-api

ee0a40a

Merge remote-tracking branch 'upstream/feature/custom-entities-api' i…

ee610d3

…nto feature/custom-entities-api

Copilot AI review requested due to automatic review settings March 28, 2026 20:50

Copilot started reviewing on behalf of onebeastchris March 28, 2026 20:50 View session

Copilot AI reviewed Mar 28, 2026

View reviewed changes

		GeyserImpl.getInstance().getLogger().debug("Client %s tried to request pack with an invalid id %s)",
		session.bedrockUsername(), id);

Uh oh!

Conversation

onebeastchris commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Additions

New Events

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes:

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

onebeastchris commented Nov 25, 2025 •

edited

Loading